JavaScript Temporal 日历转换：精通跨日历日期映射

世界不仅仅运行在公历上。全球化扩张的企业需要考虑多样化的文化和宗教习俗，而这些都与特定的历法系统息息相关。JavaScript 现代的 Temporal API 提供了强大的工具来处理这些复杂性，让开发者能够无缝地在不同日历之间映射日期，确保排程、计算和数据显示的准确性。本综合指南将探讨 Temporal API 的日历转换功能，提供实用的示例和最佳实践，以构建具备全球化意识的应用程序。

理解跨日历日期映射的需求

传统的 JavaScript `Date` 对象在处理非公历日历方面存在局限性。Temporal API 通过提供一种标准化且强大的方式来处理各种历法系统，解决了这个问题。请考虑以下场景：

• 安排国际会议： 为一个按公历安排的活动准确确定其在伊斯兰历（回历）或希伯来历中的对应日期，对于尊重宗教节日和文化敏感性至关重要。
• 计算不同地区的贷款利息： 一些金融机构使用特定的日历进行利息计算。Temporal 允许在这些系统中进行精确的日期算术。
• 以用户偏好的格式显示日期： 根据用户的地区和日历偏好定制日期显示，可以增强用户体验，特别是对于面向多元化人群的应用。
• 历史数据分析： 在处理历史数据集时，理解和转换以较旧或不常见的日历记录的日期，对于准确解释至关重要。

Temporal API 与日历简介

Temporal API 现在已在现代 JavaScript 环境中得到广泛支持，它提供了一种更直观、更强大的方式来处理日期、时间和时区。其核心是 `Temporal.Calendar` 对象，它代表一个特定的历法系统。Temporal.PlainDate、Temporal.PlainDateTime 和其他 Temporal 类型都可以与一个 `Temporal.Calendar` 实例关联。

在撰写本文时，Temporal API 目前支持以下日历：

• `iso8601`（公历 - 默认）
• `gregory`（`iso8601` 的别名）
• `islamic`
• `islamic-umalqura`
• `islamic-tbla`
• `islamic-rgsa`
• `islamic-civil`
• `hebrew`
• `buddhist`
• `roc`（民国历）
• `japanese`
• `persian`

未来的版本可能会引入更多日历或允许自定义日历实现。

使用 Temporal.PlainDate 进行基本日历转换

`Temporal.PlainDate` 对象表示一个不带时区的日期。您可以创建一个与特定日历关联的 `Temporal.PlainDate`：

const gregorianDate = Temporal.PlainDate.from('2024-01-20');
const islamicCalendar = Temporal.Calendar.from('islamic');
const islamicDate = Temporal.PlainDate.from({ year: 1445, month: 6, day: 8, calendar: islamicCalendar });

console.log(gregorianDate.toString()); // Output: 2024-01-20
console.log(islamicDate.toString());   // Output: 1445-06-08[u-ca=islamic]

`toString()` 方法将输出带有日历注释 `[u-ca=islamic]` 的日期。这表示该日期与伊斯兰历相关联。

在日历之间进行转换

在日历之间转换的关键是创建与每个日历相关联的 `Temporal.PlainDate` 对象，然后提取各自的日期组件。以下是如何将公历日期转换为其在伊斯兰历中的对应日期：

const gregorianDate = Temporal.PlainDate.from('2024-01-20');
const islamicCalendar = Temporal.Calendar.from('islamic');

// Extract date components in the Islamic calendar
const islamicYear = gregorianDate.toPlainDate(islamicCalendar).year;
const islamicMonth = gregorianDate.toPlainDate(islamicCalendar).month;
const islamicDay = gregorianDate.toPlainDate(islamicCalendar).day;

console.log(`Gregorian: ${gregorianDate.toString()}`);
console.log(`Islamic: ${islamicYear}-${islamicMonth}-${islamicDay}`); // Output: Islamic: 1445-6-8

让我们分解一下这个例子：

1. 我们从一个表示为 `Temporal.PlainDate` 对象的 `gregorianDate` 开始。
2. 我们使用 `Temporal.Calendar.from('islamic')` 创建一个 `islamicCalendar` 对象。
3. 核心转换通过 `gregorianDate.toPlainDate(islamicCalendar)` 完成。这将创建一个新的 `Temporal.PlainDate` 对象，它代表相同的时间点，但现在与伊斯兰历相关联。
4. 我们从转换后的 `Temporal.PlainDate` 对象中提取 `year`、`month` 和 `day` 组件。

您可以调整此模式以在 Temporal API 支持的任意两种日历之间进行转换。

高级日历处理：伊斯兰历

伊斯兰历有几种变体。Temporal API 支持这些变体：

• `islamic`：通用的伊斯兰历（实现可能有所不同）。
• `islamic-umalqura`：基于沙特阿拉伯的乌姆·库拉历。
• `islamic-tbla`：基于表格计算。
• `islamic-rgsa`：基于宗教总秘书处（埃及）。
• `islamic-civil`：伊斯兰历的纯算术版本，主要用于计算。

在使用伊斯兰历时，了解哪种变体适合您的用例至关重要。例如，对于沙特阿拉伯的宗教活动，您可能需要使用 `islamic-umalqura`。对于财务计算，由于其可预测性，`islamic-civil` 可能更合适。

const gregorianDate = Temporal.PlainDate.from('2024-03-11');
const islamicUmalquraCalendar = Temporal.Calendar.from('islamic-umalqura');
const islamicCivilCalendar = Temporal.Calendar.from('islamic-civil');

const islamicUmalquraDate = gregorianDate.toPlainDate(islamicUmalquraCalendar);
const islamicCivilDate = gregorianDate.toPlainDate(islamicCivilCalendar);

console.log(`Gregorian: ${gregorianDate.toString()}`);
console.log(`Islamic (Umm al-Qura): ${islamicUmalquraDate.year}-${islamicUmalquraDate.month}-${islamicUmalquraDate.day}`);
console.log(`Islamic (Civil): ${islamicCivilDate.year}-${islamicCivilDate.month}-${islamicCivilDate.day}`);

伊斯兰历的重要注意事项：

• 伊斯兰历中新月份的开始是基于对新月牙的观测。`islamic-umalqura` 日历旨在与沙特阿拉伯的实际月相观测保持一致，但仍可能出现差异。
• `islamic-civil` 日历是一种数学近似值，不反映实际的月相观测。
• 对于伊斯兰节日的准确日期，请务必咨询相关的宗教权威机构或可靠来源。

使用希伯来历

希伯来历是一种阴阳历，用于犹太教的宗教活动，并且是以色列的官方日历。它包含闰月以使其与季节保持一致。

const gregorianDate = Temporal.PlainDate.from('2024-03-11');
const hebrewCalendar = Temporal.Calendar.from('hebrew');

const hebrewDate = gregorianDate.toPlainDate(hebrewCalendar);

console.log(`Gregorian: ${gregorianDate.toString()}`);
console.log(`Hebrew: ${hebrewDate.year}-${hebrewDate.month}-${hebrewDate.day}`);

希伯来历和 Temporal 的主要特点：

• 闰月由 Temporal API 自动处理。您无需实现用于确定闰年或添加额外月份的自定义逻辑。
• 年份编号从传统的犹太纪元（创世）开始。
• 希伯来历的月份名称与公历不同。您可以通过国际化 (i18n) 库或自定义映射来访问这些月份名称。

处理佛历、民国历、日本历和波斯历

Temporal API 也支持其他日历，每种日历都有其特殊性。以下是一些注意事项：

• 佛历： 佛历是许多东南亚国家使用的阴阳历。年份编号通常从佛陀涅槃开始。
• 民国历（中华民国）： 该日历在台湾使用，年份从 1912 年中华民国成立算起。
• 日本历： 日本历基于公历，但使用日本年号（nengō）来表示年份。
• 波斯历： 波斯历是一种阳历，主要在伊朗和阿富汗使用。

const gregorianDate = Temporal.PlainDate.from('2024-03-11');
const buddhistCalendar = Temporal.Calendar.from('buddhist');
const rocCalendar = Temporal.Calendar.from('roc');
const japaneseCalendar = Temporal.Calendar.from('japanese');
const persianCalendar = Temporal.Calendar.from('persian');

const buddhistDate = gregorianDate.toPlainDate(buddhistCalendar);
const rocDate = gregorianDate.toPlainDate(rocCalendar);
const japaneseDate = gregorianDate.toPlainDate(japaneseCalendar);
const persianDate = gregorianDate.toPlainDate(persianCalendar);

console.log(`Gregorian: ${gregorianDate.toString()}`);
console.log(`Buddhist: ${buddhistDate.year}-${buddhistDate.month}-${buddhistDate.day}`);
console.log(`ROC: ${rocDate.year}-${rocDate.month}-${rocDate.day}`);
console.log(`Japanese: ${japaneseDate.year}-${japaneseDate.month}-${japaneseDate.day}`);
console.log(`Persian: ${persianDate.year}-${persianDate.month}-${persianDate.day}`);

使用这些日历时，请注意它们的特定纪元（起始年份）以及与日期表示相关的任何文化细微差别。

Temporal.Now 与日历注意事项

虽然 `Temporal.Now` 可用于获取当前日期和时间，但重要的是要理解它默认返回 ISO 8601 日历中的当前日期和时间。如果您需要不同日历中的当前日期，则需要进行转换：

const islamicCalendar = Temporal.Calendar.from('islamic');
const now = Temporal.Now.plainDateISO(); // Current date in ISO 8601 calendar
const islamicNow = now.toPlainDate(islamicCalendar);

console.log(`Current Gregorian Date: ${now.toString()}`);
console.log(`Current Islamic Date: ${islamicNow.year}-${islamicNow.month}-${islamicNow.day}`);

日期格式化与国际化 (i18n)

转换日期只是问题的一部分。您还需要正确地格式化它们以供显示。JavaScript 的 `Intl.DateTimeFormat` API 提供了强大的国际化功能。您可以将它与 Temporal API 结合使用，以一种区域感知的方式格式化日期，同时考虑到关联的日历。

const gregorianDate = Temporal.PlainDate.from('2024-01-20');
const islamicCalendar = Temporal.Calendar.from('islamic');
const islamicDate = gregorianDate.toPlainDate(islamicCalendar);

const formatter = new Intl.DateTimeFormat('ar-SA-u-ca-islamic', { // Arabic (Saudi Arabia) with Islamic calendar
  year: 'numeric',
  month: 'long',
  day: 'numeric',
});

console.log(formatter.format(islamicDate)); // Example output: ٢٠ رجب، ١٤٤٥ هـ

让我们分析一下代码：

• `'ar-SA-u-ca-islamic'` 是区域设置字符串。`ar-SA` 指定阿拉伯语（沙特阿拉伯），`u-ca-islamic` 明确请求使用伊斯兰历。
• `Intl.DateTimeFormat` 选项控制日期的格式化方式（年、月、日）。
• `format()` 方法接受一个 `Temporal.PlainDate` 对象（在本例中为 `islamicDate`），并根据指定的区域设置和日历返回一个格式化的字符串。

您可以调整区域设置字符串和格式化选项以满足您的特定需求。例如，要以希伯来语格式化日期：

const gregorianDate = Temporal.PlainDate.from('2024-03-11');
const hebrewCalendar = Temporal.Calendar.from('hebrew');
const hebrewDate = gregorianDate.toPlainDate(hebrewCalendar);

const formatter = new Intl.DateTimeFormat('he-IL-u-ca-hebrew', { // Hebrew (Israel) with Hebrew calendar
  year: 'numeric',
  month: 'long',
  day: 'numeric',
});

console.log(formatter.format(hebrewDate));

有效日期格式化的技巧：

• 使用能准确反映用户首选语言和地区的区域设置字符串。
• 选择适合上下文的格式化选项（例如，紧凑显示使用短日期格式，详细呈现使用长日期格式）。
• 在不同区域设置下测试您的格式化，以确保准确性和可读性。

跨日历执行日期算术

Temporal API 在日期算术方面表现出色。您可以对 `Temporal.PlainDate` 对象进行日、月或年的加减运算，即使在使用非公历日历时也是如此。

const gregorianDate = Temporal.PlainDate.from('2024-01-20');
const islamicCalendar = Temporal.Calendar.from('islamic');
const islamicDate = gregorianDate.toPlainDate(islamicCalendar);

// Add 30 days to the Islamic date
const futureIslamicDate = islamicDate.add({ days: 30 });

console.log(`Original Islamic Date: ${islamicDate.year}-${islamicDate.month}-${islamicDate.day}`);
console.log(`Islamic Date + 30 days: ${futureIslamicDate.year}-${futureIslamicDate.month}-${futureIslamicDate.day}`);

// Convert the future Islamic date back to Gregorian
const futureGregorianDate = futureIslamicDate.toPlainDate('iso8601');
console.log(`Equivalent Gregorian Date: ${futureGregorianDate.toString()}`);

日期算术的关键注意事项：

• `add()` 和 `subtract()` 方法返回新的 `Temporal.PlainDate` 对象；它们不会修改原始对象。
• 在加减月份或年份时，Temporal API 会处理特定于日历的闰年和月份长度规则。
• 在执行算术运算时，请注意潜在的日期溢出或下溢。Temporal API 通常会将日期调整为该日历内最接近的有效日期。

处理模糊日期

在某些情况下，日期在日历之间转换时可能会产生歧义。当目标日历中不存在特定日期，或者目标日历中的多个日期可能对应于源日期时，就会发生这种情况。Temporal 会优雅地处理这些情况，通常返回最接近的有效日期。

例如，考虑将接近公历月末的公历日期转换为伊斯兰历，而相应的伊斯兰历月份可能更短。Temporal 会自动将结果调整为该伊斯兰历月份的最后一天。

错误处理与验证

虽然 Temporal API 很强大，但实施适当的错误处理和验证以防止意外行为至关重要。以下是一些需要考虑的常见场景：

• 无效的日历名称： 如果您向 `Temporal.Calendar.from()` 提供无效的日历名称，它将抛出 `RangeError`。捕获此错误并提供用户友好的消息。
• 无效的日期格式： 如果您尝试从无效的日期字符串创建 `Temporal.PlainDate`，它将抛出 `RangeError`。在将日期字符串传递给 `Temporal.PlainDate.from()` 之前进行验证。
• 不支持的操作： Temporal API 可能不支持某些特定于日历的操作。请查阅您正在使用的特定日历的文档。

跨日历日期映射的最佳实践

为确保在使用跨日历日期映射时的准确性和可维护性，请遵循以下最佳实践：

• 使用 Temporal API： Temporal API 提供了一种标准化且强大的方式来处理日历转换。避免为此目的使用旧版的 JavaScript `Date` 对象。
• 明确指定日历： 在创建 `Temporal.PlainDate` 对象时，务必明确指定日历。这可以防止歧义，并确保应用正确的日历规则。
• 选择正确的伊斯兰历变体： 了解各种伊斯兰历实现之间的差异，并选择最适合您用例的一种。
• 使用国际化 (i18n)： 利用 `Intl.DateTimeFormat` API 以区域感知的方式格式化日期。
• 实施错误处理： 实施强大的错误处理以捕获无效的日历名称、日期格式和其他潜在问题。
• 全面测试： 使用各种日期和区域设置测试您的代码，以确保准确性和兼容性。
• 保持更新： Temporal API 仍在发展中。请随时关注最新的规范和浏览器实现。

结论

JavaScript 的 Temporal API 彻底改变了我们处理日期和日历的方式，为执行跨日历日期映射提供了一种强大且标准化的方法。通过理解不同历法系统的细微差别并有效利用 Temporal API，开发者可以构建具备全球化意识的应用程序，以满足多样化的文化和宗教需求。拥抱 Temporal API，在您的项目中创建更具包容性和准确性的日期处理解决方案。

本指南全面概述了使用 JavaScript Temporal API 进行日历转换。请记住查阅官方 Temporal API 文档以获取最新信息和详细规范。